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Preface 


Intended Audience 

This manual is intended for all programmers using VAX RMS data files. This 
audience includes high-level language users who use only their language's 
input/output statements. 


Structure of This Document 

This document is composed of four major sections. 

The Format Section is an overview of the Convert and Convert/Reclaim 
utilities and is intended as a quick reference guide. The format summary 
contains the DCL commands that invoke the Convert and the Convert 
/Reclaim utilities, and lists all command qualifiers and parameters. The usage 
summary describes how to invoke and exit from the Convert and Convert 
/Reclaim utilities, how to direct output, and any restrictions you should be 
aware of. 

The Description Section explains how to use the Convert and Convert 
/Reclaim utilities. 

The Qualifier Section describes each DCL command qualifier. Qualifiers 
appear in alphabetical order. 

The Examples Section contains examples of common operations that you 
perform with the Convert and Convert/Reclaim utilities. 


Associated Documents 

To use the Convert and Convert/Reclaim Utility, you should also be familiar 
with the following manuals: 

• Guide to VAX/VMS File Applications 

• VAX/VMS Analyze/RMS—File Utility Reference Manual 

• VAX/VMS File Definition Language Facility Reference Manual 


Conventions Used in This Document 


Convention Meaning 

I RET | A symbol with a one- to three-character 

abbreviation indicates that you press a key on 
the terminal, for example, |ret| . 

1 ctrl/x 1 The phrase CTRL/x indicates that you must press 

the key labeled CTRL while you simultaneously 
press another key, for example, CTRL/C, CTRL/Y, 
CTRL/O. 
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Convention 

Meaning 

$ SHOW TIME 
05-JUN-1985 11:55:22 

Command examples show all output lines or 
prompting characters that the system prints 
or displays in black letters. All user-entered 
commands are shown in red letters. 

$ TYPE MYFILE.DAT 

Vertical series of periods, or ellipsis, mean either 
that not all the data that the system would display 
in response to the particular command is shown or 
that not all the data a user would enter is shown. 

file-spec,... 

Horizontal ellipsis indicates that additional 
parameters, values, or information can be entered. 

[logical-name] 

Square brackets indicate that the enclosed item 
is optional. (Square brackets are not, however, 
optional in the syntax of a directory name in a 
file specification or in the syntax of a substring 
specification in an assignment statement.) 

quotation marks 
apostrophes 

The term quotation marks is used to refer to 
double quotation marks ("). The term apostrophe 
(') is used to refer to a single quotation mark. 
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New and Changed Features 


The following enhancements are included in this version of the Convert and 
Convert/Reclaim Utility: 

• Supports enhancements to Prolog 3 ISAM files: alternate keys; key and 
index compression for alternate keys; and the new nonstring data types 
BIN8 and INT8. 

• Uses SORT-32, which is more flexible since it uses smaller work files. 
SORT is now a shareable image, is twice as fast, and signals errors directly 
to the user. 
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CONVERT 


CONVERT 




The Convert Utility (CONVERT) copies records from one or more 
files to an output file, changing the record format and file organiza- 


tion to those of the output file. 



The Convert/Reclaim Utility (CONVERT/RECLAIM) reclaims empty 
buckets in Prolog 3 indexed files so that new records can be written 


in those buckets. 


CONVERT 

FORMAT 

CONVERT input-file-spec[,. 

output-file-spec 

Command Qualifiers 

Defaults 


/[NOJAPPEND 

/NOAPPEND 


/[NOJCREA TE 

/CREATE 


/[NO]EXCEPTIONS—FILE[=file-spec] 

/NOEXCEPTIONS—FILE 


/[NOJEXIT 

/NOEXIT 


/[NOJFAST— LOAD 

/FAST-LOAD 


/FDL=fdl-file-spec 

None. 


/[NOJFILL _BUCKETS 

/NOFILL -BUCKETS 


/[NO]FIXED—CONTROL 

/NOFIXED—CONTROL 


/KEY=n 

/KEY=0 


/MERGE 

None. 


/[NO]PAD[=[%b]x] 

/NOPAD 


/PROLOG=n 

None. 


/[NOJREAD—CHECK 

/NOREAD-CHECK 


/[NOJSHARE 

/NOSHARE 


/[NOJSORT 

/SORT 


/[NOJSTA TISTICS 

/NOSTATISTICS 


/[NOJTRUNCA TE 

/NOTRUNCATE 


/WORK— FILES-=n 

/WORK -FILES=2 


/[NOJWRITE—CHECK 

Command Parameters 

/NOWRITE-CHECK 


input-file-spec [,...] 

Specifies the file or files to be converted. 

The specifications may not contain 


wildcard characters. Multiple input files 

are concatenated to form a single 


output file. You may specify up to 10 input files. 


output-file-spec 



Specifies the file into which the converted records are to be written. If the file 
specification does not include a file type, CONVERT assumes the file type of 


the first input file. 



CONVERT 

/RECLAIM 

FORMAT 


CONVERT/RECLAIM file-spec 


Command Qualifier Default 

/[NOJSTA TISTICS /NOSTATISTICS 
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CONVERT 

Description 


Command Parameter 

file-spec 

Specifies the Prolog 3 indexed file in which you want to reclaim buckets. 
The file cannot be opened for shared access when you give the CONVERT 
/RECLAIM command. 


usage summary Invoking 

Invoke the Convert Utility by typing the CONVERT command at the DCL 
level. 

Likewise, invoke the Convert/Reclaim utility by typing the CONVERT 
/RECLAIM command at the DCL level. 

Exiting 

Exit both the Convert and the Convert/Reclaim utilities by letting the utility 
run to successful completion. 

Directing Output 

Output from the Convert Utility is directed to the file you indicated with the 
output-file-spec parameter. For more information, see Section 1. 

The Convert/Reclaim Utility, however, produces no output unless the 
/STATISTICS command qualifier is specified. 

Privileges/Restrictions 

NETMBX privilege is required if you want to execute either CONVERT or 
CONVERT/RECLAIM over a network. 


DESCRIPTION The Convert Utility (CONVERT) copies records from one or more source data 

files to a second output data file, which can differ in file organization and 
format from the first. 

You can also use CONVERT to reformat an indexed file in which you have 
deleted or inserted many records. The file specification is used as both the 
input and the output file specification. In this case, the output file will have 
a version number that is one greater than the highest existing version of the 
input file. During such reorganizations, CONVERT establishes new record's 
file addresses (RFAs) for the records. 

On the other hand, the Convert/Reclaim Utility (CONVERT/RECLAIM) finds 
empty buckets in a Prolog 3 ISAM (indexed) file and makes them usable 
again by reclaiming them. As opposed to CONVERT, CONVERT/RECLAIM 
preserves existing RFAs for the file. 

A set of library routines can also perform the functions of both the Convert 
and the Convert/Reclaim utilities from within a program. For more infor¬ 
mation, refer to the CONVERT Routines in the VAX/VMS Utility Routines 
Reference Manual. 

This description covers the following topics. Section 1 explains how to 
produce output files with CONVERT. Section 2 describes converting between 
carriage control formats. Section 3 discusses using CONVERT with DECnet- 
VAX. Section 4 explains how to handle any exception conditions you may 
receive from CONVERT. Section 5 gives a comparison of CONVERT with 
RMSCNV/RMSIFL. And Section 6 explains how to use the Convert/Reclaim 
Utility. 
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CONVERT 

Description 


1 Output Files 

There are two ways to generate a reformatted and reorganized output file. 
CONVERT can either create an output file or load an existing one. 

If you want to create an output file with different characteristics than the 
input file, you specify an FDL (File Definition Language) file specification in 
the command line. To create an output file with the same characteristics as 
the first input file, you omit the /FDL qualifier. 

If the output file exists, it can either be empty or it can contain records. If the 
output file is sequential, then specifying the /APPEND qualifier will cause 
new records from the input file to be added sequentially to the end of the 
output file. 

However, if the existing output file is indexed and contains records, then 
specifying the /MERGE qualifier will cause new records from the input file to 
be merged in their proper order. 

In addition, sorting the records from an input ISAM (indexed) file can be 
costly in terms of processing time and disk space. If the records in the input 
file are already in sequential order by primary key (KEY=0), then specify the 
/NOSORT qualifier with the CONVERT command. For more information on 
sorting ISAM files, see both the /FAST_LOAD and the /SORT qualifiers in 
the Command Qualifiers Section. 


2 Converting Carriage Control Formats 

A file can have one of four carriage control formats: 

• CARRIAGE-RETURN 

• FORTRAN 

• PRINT 

• NONE 

These formats are all represented differently, so when you are convert¬ 
ing a file from one carriage control format to another, the carriage control 
information has to be translated. 

This translation is especially important when you are converting to or from a 
file with the FORTRAN format. Records with the FORTRAN format contain 
one byte of carriage control information at the beginning of each record. 

For most conversions, the FORTRAN carriage control information is preserved 
as the first data byte of the record, and the printing characteristics are lost. 
However, certain conversions can preserve the printing characteristics of 
the FORTRAN carriage control information. When FORTRAN carriage 
control is converted to the equivalent PRINT carriage control, the information 
preceeding each FORTRAN record is changed but not lost. 

On the other hand, when PRINT carriage control is converted to FORTRAN 
carriage control, certain characters that give carriage control information to 
the printer cannot be translated exactly. So these untranslatable characters 
are represented as a single-spaced FORTRAN record. 


CONV-3 








CONVERT 

Description 


When FORTRAN carriage control is converted to STREAM, control charac¬ 
ters affecting carriage returns (<CR>), line feeds (<LF>), and form feeds 
(<FF>) are prefixed and appended to each FORTRAN record. These char¬ 
acters may affect the STREAM output because they are considered record 
delimiters for stream files. As a result, you may have a different number of 
records in the STREAM output file, and some of the records may be null 
records. 

Below is a chart showing how FORTRAN carriage control information trans¬ 
lates to STREAM. 




STREAM Format Equivalent 

FORTRAN 

Hex Code 

Characters 

Characters 

Format 

Equivalent 

Prefixed 

Appended 

1 

31 

<FF> 

<CR> 

0 

30 

<LF> <LF> 

<CR> 

space 

20 

<LF> 

<CR> 

$ 

24 

<LF> 

Nothing appended 

+ 

2B 

Nothing prefixed 

<CR> 

null 

00 

Nothing prefixed 

Nothing appended 


All other conversions from FORTRAN preserve the carriage control informa¬ 
tion as data. On the other hand, all other conversions to FORTRAN prefix 
the converted records with the ASCII space character to obtain single spacing. 

For more information on carriage control, see the description of the FDL 
Facility in the VAX/VMS Utilities Reference Volume. 


3 Using CONVERT With DECnet-VAX 

You can use the CONVERT command to copy and retrieve files to and from 
a remote node, either with or without modifying file attributes. If the output 
file exists, the Convert Utility changes the organization and format of the 
input data file to that of the output file. If the output file does not exist, 
CONVERT creates it from the file attributes specified in an FDL file. On the 
other hand, you can use the Convert Utility to copy files to or from a remote 
node without modifying file attributes. CONVERT transfers the file record by 
record, just as it does on a single node. However, you must have NETMBX 
privilege to execute CONVERT over a network. 

Along the same line, you can use CONVERT/RECLAIM to reclaim empty 
buckets in Prolog 3 indexed files from a remote node. 


4 Exception Conditions 

Certain conversions cause exception conditions. An exception condition 
occurs when a record from the input file cannot be placed in the output file 
because of some format incompatibility. CONVERT sends a warning error 
message to SYS$ERROR upon encountering a record that causes an exception 
condition. 
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CONVERT 

Description 


For example, an exception condition occurs when the length of the input 
records exceeds the length you specified for fixed-length output records. 

You can avoid this exception condition by specifying the /TRUNCATE 
qualifier. Converting short fixed-length records into longer fixed-length 
records also causes an exception. To avoid this exception condition, use the 
/PAD qualifier to fill in the output records. The /PAD qualifier allows you to 
specify your choice of pad character. 

To keep a copy of the exception records, you create an exceptions file with 
the /EXCEPTIONS_FILE qualifier. The exceptions file is a sequential file 
with variable-length records; it receives a copy of any record that cannot be 
placed in the output data file. Exceptions files are given the file type EXC by 
default. 


5 CONVERT and RMSCNV/ RMSIFL 

The VAX/VMS Convert Utility is a native-mode superset replacement for 
both the RMS-11 RMSIFL and RMSCNV compatibility mode utilities. Tables 
CONV-1 and CONV-2 compare the functions of the Convert Utility with the 
RMSCNV and RMSIFL utilities, respectively. 


Table CONV-1 RMSCNV Functions and VAX/VMS Convert 
Utility 


RMSCNV Switch 

CONVERT Equivalent 

Description 

/ID 

NA 

Identifies current 
version of CNV. 

/SL:[filespec] 

/STATISTICS 

Provides summary list. 

To get a listing file, 
assign a file to 
SYSSOUTPUT. 

/AP 

/APPEND 

Appends records to a 
a sequential file. 

/BL[:nnn] 

Specify block 
size with FDL. 

Sets block size on 
magnetic tape. 

/FO:val 

Specify organ¬ 
ization with FDL. 

Sets output file 
organization. 

/LO 

/NOFILL_ BUCKETS 

Follows fill numbers 
when loading file. 

/MA 

NA 

Uses mass insert. 

/PD[:[#]x] 

/PAD[=[%b]x] 

Pads input records. 

/SU 

Specify with FDL. 

Supersedes existing 
file. 

/TR 

/TRUNCATE 

Truncates input 
records. 

/WR 

/FIXED-CONTROL 

Writes or reads fixed 
control area. 

/KR:n 

/KEY=n 

Reads the input file 
by key. 
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CONVERT 

Description 


Table CONV-2 RMSIFL Functions and VAX/VMS Convert 
Utility 


RMSIFL Switch 

CONVERT Equivalent 

Description 

/ID 

NA 

Identifies current 
version of IFL. 

/ER[:file-spec] 

/EXCEPTIONS—FILE 

[=file-spec] 

Writes exception 
records to a file. 

/LO 

/NOFILL_ BUCKETS 

Follows fill numbers 
when loading file. 

/NOER[:s] 

/EXIT 

Stops immediately if 
there is an exception. 

/PD[:[#]x) 

/PAD[=[%b]x] 

Pads input records. 

/TR 

/TRUNCATE 

Truncates input 
records. 

/CL:nnn 

NA 

Sets sort work files 
cluster size; specific 
to RSTS/E. 

/DE:dvn[:dvn] 

Assign the 
logical names 

SORTWORKn (n = 0-9). 

Reassigns devices for 
sort work files. 

/KR:n 

/KEY=n 

Reads the input file 
by key. 

/NOSO 

/NOSORT 

Does not sort file 
before loading. 


6 Using the Convert/ Reclaim Utility 

Unlike CONVERT, which changes the organization and record format of a 
file, CONVERT/RECLAIM reclaims empty buckets in an existing Prolog 3 
ISAM file. The organization and record format of the file are not changed. 

When you delete all of the records in a bucket, the bucket still retains its 
position within the database because it has a certain range of primary key 
values associated with it. When you then write new records to the file, those 
records whose primary key falls within that range will be written to that 
bucket. 

If your application contains new records that will never use a primary key 
that belonged to an old deleted record, then empty buckets will never be 
reused unless you reclaim them. To reclaim a bucket, CONVERT/RECLAIM 
deletes the old pointers to it and puts it on a list of free buckets. When an 
application adds records and needs a bucket, RMS goes to the free bucket list 
and sets up pointers to a bucket from the list. By reclaiming buckets, you can 
often avoid extending the file, which causes inefficient processing. 

In addition, CONVERT/RECLAIM preserves RFA (record's file address) 
access to the file. 
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CONVERT 

Description 


CONVERT/RECLAIM cannot be used on Prolog 1 or 2 ISAM (indexed) files. 
To reclaim empty buckets in a Prolog 1 or 2 indexed file, you must first 
reorganize the file by using the Convert Utility. This reorganization creates a 
new version of the file. However, unlike CONVERT/RECLAIM, CONVERT 
establishes new RFAs for the records. 

To invoke the CONVERT/RECLAIM functions from within a program, use 
the CONV$RECLAIM routine. For more information, refer to the VAX/VMS 
Utility Routines Reference Manual. 
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CONVERT 

Command Qualifiers 


COMMAND 

QUALIFIERS 


The CONVERT command qualifiers, which allow you to select the 
organization and format of your output file, are described in the following 
section. 
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CONVERT 

/APPEND 


/APPEND 

Controls whether records are to be appended to the end of an 
existing sequential file. 

FORMAT 

/[NO]APPEND 

qualifier values 

None. 

DESCRIPTION 

The /APPEND qualifier is useful when you merely want to attach one file to 
the end of another file. This qualifier is ignored when the file's organization 
is relative or indexed. 


/NOAPPEND, however, is the default. You should use this option when 
you are loading records into a sequential file that already contains records or 
when you are creating a new sequential file. 


If both /APPEND and /CREATE are specified, /APPEND overrides the 
/CREATE qualifier. 


EXAMPLE 


$ CONVERT/APPEND N_Z_FILE.DAT A_M_FILE.DAT 

This command causes the sequential input file N_Z__FILE.DAT to be attached 
to the end of the sequential file A__M_JFILE.DAT. In this case, the records in 
two files are already in alphabetical order, and N_Z_JFILE.DAT only needs 
to be appended to A__M_FILE.DAT for the whole file to be in alphabetical 
order. 


COIMV-9 









CONVERT 

/CREATE 


/CREATE 

Determines whether CONVERT creates a file or uses an existing file 
for output. 

FORMAT 

/[NO]CREATE 

qualifier values 

None. 

DESCRIPTION 

/CREATE causes CONVERT to create an output file instead of using an 
existing file for output. 

If the output file is to have different characteristics from the input file, you 
must also specify the /FDL qualifier. To create an output file with the same 
characteristics as the input file, omit the /FDL qualifier. 

/NOCREATE causes CONVERT to use an existing file for output. You would 
use this option, for instance, to load records into a data file that you had 
previously created with the Create/FDL Utility. 

/CREATE is the default. 


EXAMPLES 

□ $ CONVERT/CREATE OLDFILE.DAT NEWFILE.DAT 

This command creates the new output file NEWFILE.DAT and loads it with 
the records from OLDFILE.DAT. 

0 $ CONVERT/CREATE/FDL=UPDATE.FDL OLDFILE.DAT NEWFILE.DAT 

This command creates the new output file NEWFILE.DAT and loads it with 
the OLDFILE.DAT records that have been reformatted according to the 
characteristics in the FDL file UPDATE. 
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CONVERT 

/EXCEPTIONS-FILE 


/EXCEPTIONS—FILE 

Specifies whether an exceptions file is to be generated during the 



conversion. 

FORMAT 

/EXCEPTIONS_FILE [= file-specJ 
/NOEXCEPTIONS—FILE 

qualifier value 

file-spec 

Specifies the output file into which you want the exception records to be re¬ 
turned. If you specify /EXCEPTIONS_FILE and omit the file-spec parameter, 
the exception records are displayed to SYS$OUTPUT. 

The default file type for the exceptions file is EXC. /NOEXCEPTIONS_FILE 
is the default. 


EXAMPLE 

$ CONVERT/EXCEPTIONS_FILE=EXFILE.EXC OLDFILE.DAT NEWFILE.DAT 

This command loads the records from OLDFILE.DAT to NEWFILE.DAT and 
writes any records that cause exceptions into the file EXFILE.EXC. 
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CONVERT 

/EXIT 


/EXIT 

Controls whether CONVERT will exit when it encounters an ex¬ 
ception record. The default operation is to continue processing 
records. 

FORMAT 

/[NO]EXIT 

qualifier values 

None. 


EXAMPLE 

$ CONVERT/EXIT OLDFILE.DAT NEWFILE 

This command loads the records from OLDFILE.DAT into NEWFILE.DAT 
and causes CONVERT to exit if an exception record is processed. Since an 
output file type was not specified, CONVERT gives the output file the same 
file type as the input file. 
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CONVERT 

/FAST_LOAD 


/FAST_LOAD 


Specifies whether a fast loading algorithm will be used for indexed 
files. 


FORMAT /[NO]FAST_LOAD 


qualifier values None. 




DESCRIPTION The /FAST-LOAD option is one of the most useful features of the Convert 

Utility. Both /FAST_LOAD and /NOFAST_LOAD sort primary keys, and 
both require multiple scratch disk files. 

Essentially, the difference between the /NOFAST—LOAD and the 
/FASTLOAD options is how records are inserted into an ISAM (indexed) 
file. The /NOFAST_LOAD option uses the normal RMS Put service to load 
each record; RMS updates the indexes of both the primary and secondary 
(alternate) keys as each record is inserted. 

The major disadvantage of using the /NOFAST_LOAD option is the slower 
performance of the system that results from bucket splits and updates to 
the index. As each primary key is inserted, any secondary keys for that 
record are also inserted, but in the order of the primary key. In other words, 
the secondary keys are not inserted in order of their own keys. These 
unsorted secondary keys may eventually cause bucket splits; as a result, the 
index structure for the secondary keys may be less efficient. However, the 
advantage of the /NOFAST_LOAD option is that secondary keys are not 
sorted. 

The /FAST_LOAD option, on the other hand, sorts both the primary and 
secondary keys. CONVERT processes a file as follows: 

1 The primary keys are sorted. If the input file is on tape or if you specify 
multiple input files, the temporary sort work file contains the actual 
records in sorted order. If the input file is on a disk, however, the work 
file contains only pointers in sorted order back to the input file. 

Note: If your input records are already in order by primary key or if the 
primary key of the input and output ISAM files is the same, you 
should specify /NOSORT. This qualifier ensures that the primary 
keys are not sorted again. For more information on sorting, see the 
description of the /SORT qualifier in this section. 

2 CONVERT builds the primary data record level from the sorted output 
file. CONVERT completely fills a bucket with data before it creates the 
lowest primary index level (the level 1 index). When an index bucket is 
filled, CONVERT creates an index record in the next highest index level. 

3 When CONVERT is finished with the primary key, it updates the associ¬ 
ated KEY DESCRIPTOR in the file's prolog, closes any input files, deletes 
any temporary files, and closes the output file. At this point, CONVERT 
has created a valid output file, sorted in order of the primary key. If you 
have not specified any alternate keys, CONVERT is finished processing. 
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CONVERT 

/FAST_LOAD 


4 CONVERT now reopens the input file so the first alternate key (if one 
has been specified) can be sorted. Again, CONVERT creates a temporary 
file containing pointers back to the primary data records. These pointers, 
however, have been sorted according to the first alternate key. 

5 CONVERT loads these sorted pointers into the secondary index data 
record (SIDR) level and adjusts them to point to the records in the primary 
data level. Again, CONVERT completely fills a bucket with data before it 
creates the lowest secondary index level. When an index bucket is filled, 
CONVERT creates an index record in the next highest secondary index 
level. 

6 When CONVERT is finished with this secondary key, it updates the 
associated KEY DESCRIPTOR in the file's prolog, closes any input files, 
deletes any temporary files, and closes the output file. At this point, 
CONVERT has created a valid output file, containing sorted primary 
keys and secondary keys. If you have not specified any more alternate 
keys, CONVERT is finished processing. However, if you have specified 
additional alternate keys, they are processed in the same way. 

The major advantage of using the /FAST—LOAD option is that it is consider¬ 
ably faster than the RMS method used by the /NOFAST—LOAD option. In 
most cases, you can increase processing speed by a factor of 10. Even greater 
speed results when you load large files with many keys. 

In addition, the index structure can be very efficient because each key is 
sorted before loading. The only disadvantage is the large amount of space 
needed for the work files. However, you can control the amount of space 
by using the /WORK— FILES qualifier and by reassigning the work files to 
different devices. See the /WORK —FILES qualifier in this section for more 
information. 

The default /FAST—LOAD. 


EXAMPLES 

Q $ CONVERT/FAST.LOAD UPDATE.DAT MASTER.DAT 

This command loads the records from the file UPDATE.DAT into the output 
file MASTER.DAT using the /FAST option. SORT32 sorts the primary keys 
before they are loaded into the primary index, and CONVERT sorts the 
secondary keys in order of the primary key. 

S $ CONVERT/NOFAST.LOAD UPDATE.DAT MASTER.DAT 

This command loads the records from the file UPDATE.DAT into the output 
file MASTER.DAT using the normal RMS Put service (record-by-record). 
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/FDL 


/FDL 

indicates that an FDL file is to be used in creating the output file. 

FORMAT 

/FDL =fdl-file-spec 

qualifier value 

fdl-file-spec 

Specifies the particular FDL file to be used in creating the output file. 

DESCRIPTION 

The newly created output file will have the name specified by the output-file- 
spec command parameter; this name overrides any file name specified in the 
FDL file. 

The default file type for the FDL file is FDL. 


EXAMPLE 

$ CONVERT/FDL=INDEXFILE CUSTSEQ.DAT CUSTIND.DAT 

This command creates the new file CUSTIND.DAT according to the spec¬ 
ifications in the FDL file INDEXFILE.FDL. Records are then loaded from 
CUSTSEQ.DAT into CUSTIND.DAT. 
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CONVERT 

/FI LI_BUCKETS 


/FILL-BUCKETS 

Controls whether to override the bucket fill percentage parameter 
associated with the output file. 

FORMAT 

/[NO]FILI_BUCKETS 

qualifier values 

None. 

DESCRIPTION 

If /FILL—BUCKETS is specified, CONVERT will fill the buckets of the output 
file with as many records as possible. This behavior is advantageous if you 
do not plan to do random file processing because fewer buckets save space 
and processing time. 

With /NOFILL-BUCKETS, however, CONVERT does not fill the buckets 
completely. Therefore, you can add records at a later date without splitting 
buckets or extending the file. 

This option is valid only for indexed output files. The default is 
/NOFILL-BUCKETS. 


EXAMPLE 


$ CONVERT/FILL_BUCKETS SALES_DATA.DAT CUST_DATA.DAT 

This command loads the records from the ISAM (indexed sequential) file 
SALES_DATA.DAT into the ISAM file CUST_DATA.DAT, filling the buckets 
of the output file with as many records as possible. 
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CONVERT 

/FIXED-CONTROL 


/FIXED_CONTROL 



Controls the behavior of CONVERT in conversions between vari¬ 
able with fixed-length control (VFC) records and records of other 
formats. 

FORMAT 

/[NO]FIXED_CONTROL 

qualifier values 

None. 

DESCRIPTION 

If /FIXED_CONTROL is specified for VFC input records, then the fixed- 
control portion of the record is attached to the front of the output record. 

If /FIXED_CONTROL is specified for VFC output records, then the fixed- 
control portion of the output record is taken from the front of the input 
record. If the input record is not long enough to fill the control portion of the 
output record, an exception record is generated. 

If /NOFIXED_CONTROL is specified with VFC input records, then the 
fixed-portion of the input record is not copied to the output record. 

If /NOFIXED—CONTROL is specified for VFC output records, then the 
fixed-portion of the output record is set to 0. 

This option is not applicable to indexed files. The default is /NOFIXED— 
CONTROL. 

When you use this qualifier, you must account for the size of the fixed-control 
area when you calculate the maximum size of the output record. 


EXAMPLE 

$ CONVERT/FIXED_CONTROL VFC_FILE.DAT OUTFILE.DAT 

This command loads the VFC records in the input file VFC_FILE.DAT into 
the output file OUTFILE.DAT. 
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CONVERT 

/KEY 


/KEY 

Specifies that CONVERT use a key of reference (such as primary 
key, first alternate key, or second alternate key) to access records 
from an indexed file. 

FORMAT 

/KEY=n 

qualifier value 

n 

Specifies the key of reference by which records are accessed from an indexed 
file. For instance, you specify a primary key as /KEY= 0, a first secondary key 
as /KEY=1, and so on. 

DESCRIPTION 

The /KEY option is valid for indexed input files only. If an indexed out¬ 
put file is specified, then /NOFAST_LOAD and /NOSORT must also be 
specified. 

If you use the /KEY qualifier, you must specify a key value (/KEY=0, 
/KEY=1, and so on). If you do not specify the /KEY qualifier, the default is 
the primary key (/KEY=0). 


EXAMPLES 

□ $ CONVERT/NOCREATE CUST_SEQ.DAT CUST_ISAM.DAT 

This command loads the records from the sequential input file CUST_ 
SEQ.DAT into the indexed output file CUST_ISAM.DAT. Since the /KEY 
qualifier was not specified, the records in the output file are in order by the 
primary key. The command below would have the same effect. 

CONVERT/NOCREATE/KEY=0 CUST_SEQ.DAT CUST_ISAM.DAT 
E $ C0NVERT/N0CREATE/KEY=1 CUST_ISAM.DAT CUST_SEQ.DAT 

This command loads the records from the indexed input file CUST_ 
ISAM.DAT into the sequential output file CUST_SEQ.DAT. The records 
in the output file are in order by the first alternate key. 
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CONVERT 

/MERGE 


/MERGE 

Specifies that records are to be inserted into their proper position in 
an existing indexed file. 

FORMAT 

/MERGE 

qualifier values 

None. 

DESCRIPTION 

The /MERGE qualifier is also useful when your input records are not sorted, 
and you do not want them to be sorted as they are loaded into an output file. 

If both /MERGE and /CREATE are specified, /MERGE overrides the 
/CREATE qualifier. 


EXAMPLE 

$ CONVERT/MERGE ACCOUNTS.DAT MASTER.ISAM.DAT 

This command loads the records from the input file ACCOUNTS.DAT into 
the existing indexed output file MASTER_ISAM.DAT according to primary 
key values. 
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CONVERT 

/PAD 


/PAD 

Determines whether short records are to be padded. 

FORMAT 

/PAD [=[%b]x] 

/NOPAD 

qualifier values 

%b 

Represents the base of the numeric value specified by x. Values for b are 
listed below. 

D Indicates that x is a decimal value. 

0 Indicates that x is an octal value. 

X Indicates that x is a hexadecimal value. 

If you specify x as a numeric value, it is interpreted in the base indicated by 

%b. 

* 

X 

Specifies that the short records are to be padded with either ASCII characters 
(A through Z, a through z) or numeric values (0 through 9). 

If you specify x as an ASCII character, you do not need to specify %b. 
However, if you specify x as a numeric value, you must specify the optional 
base with %b. 

DESCRIPTION 

The /PAD qualifier indicates that short records are to be padded with ASCII 
characters. A record is too short when it does not contain as many bytes as 
the record length for fixed-length record format. 

If /PAD is specified, the default pad character is the ASCII null character 
(character value 0). The /PAD option is valid only for fixed-output record 
formats. 

The default is /NOPAD, which generates an exception record when a short 
record is encountered. 


EXAMPLES 

□ $ C0NVERT/N0CREATE/PAD=%X40 INFILE.DAT OUTFILE 

This command specifies that any short records in the input file INFILE.DAT 
are to be padded with an ASCII space character before being loaded into the 
fixed-length output file OUTFILE.DAT. 

S $ CONVERT/FDL=FIXED/PAD=0 INFILE.VAR OUTFILE.FIX 

This command creates the fixed format file OUTFILE.FIX and then loads it 
with records from the variable input file INFILE.VAR. Any short records from 
the input file are padded with an ASCII 0 before they are loaded. 
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CONVERT 

/PROLOG 


/PROLOG 

Specifies the prolog version number of the output indexed file. 

FORMAT 

/PROLOG=n 

qualifier value 

n 

Specifies the prolog number 1, 2, or 3. 

If you specify 2 for n, the output file will be either a Prolog 1 or Prolog 2 file. 

If you specify 3, CONVERT creates a Prolog 3 file for output. Prolog 3 
files accept multiple keys (or alternate keys), all data types, and segmented 
keys. The only restriction in using a Prolog 3 file applies to files containing 
overlapping key segments. In this case, you would have to use a Prolog 2 
file. However, if you try to create a Prolog 3 file when your file contains 
overlapping key segments, CONVERT returns a fatal error message, and the 
conversion does not occur. 

DESCRIPTION 

If you do not specify the /PROLOG qualifier, CONVERT uses the prolog 
version of the first input file. If the input file is not indexed, CONVERT uses 
the RMS default. To see what this default is on your system, issue the DCL 
command SHOW RMS—DEFAULT. 

The /PROLOG qualifier overrides the value given with the FDL attribute KEY 
PROLOG. 


EXAMPLE 

$ C0NVERT/PR0L0G=3 INFILE.2 0UTFILE.3 

This command loads the records from the Prolog 2 input file INFILE_2 into 
the Prolog 3 output file OUTFILE_3. Both the input and output file are 
indexed files. 
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CONVERT 

/READ_CHECK 


/READ-CHECK 



Specifies whether each input record is to be read from the file a 
second time and compared to the record originally read. 

The default is /NOREAD—CHECK. 

FORMAT 

/[NO]READ_CHECK 

qualifier values 

None. 


EXAMPLE 

$ CONVERT/READ.CHECK Q3_SALES.DAT YTD_SALES.DAT 

This command specifies that the records from the input file Q3_SALES.DAT 
are to be read and checked by the ACP, and then loaded into the output file 
YTD_SALES.DAT. 
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CONVERT 

/SHARE 


/SHARE 

Specifies whether the input file is to be opened for sharing with 
other processes. 

FORMAT 

/[NO]SHARE 

qualifier values 

None. 

DESCRIPTION 

You can use the /SHARE option to generate a rough backup of a file which 
is always opened for sharing by some applications. However, another process 
can alter the records at the same time that CONVERT is operating. As a 
result, the consistency of the output file cannot be guaranteed. 


EXAMPLE 

$ CONVERT/SHARE SYSUAF.DAT BACKUP.DAT 

This command indicates that the input file SYSUAF.DAT is open for sharing 
with other processes at the same time its records are being loaded into the 
output file BACKUP.DAT. 
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CONVERT 

/SORT 


/SORT 

Specifies whether the input file is to be sorted before being loaded 
into an indexed file. The sort is done according to the primary key 
of the output file. 

FORMAT 

/[NO]SORT 

qualifier values 

None. 

DESCRIPTION 

Two procedures can improve the sort performance: 

• Increasing the size of the working set for the duration of the sort. The 
general rule is to use as large a working set as allowed by your working 
set quota. To set this value, use the DCL command SET WORKING—SET. 
To see what your authorized quota is, give the SHOW WORKING—SET 
command. 

• Placing the input file, the output file, and the temporary work files on 
separate disk devices. The default operation is to place the work files on 
your default device, which could conceivably cause CONVERT to run out 
of disk space. To specify the location of the work files, give a command of 
the form 

$ ASSIGN device-name: SORTWORKn 

The "n" represents the number of the work file, from 0 to 9. The colon is 
required after the device name. For example, the following two ASSIGN 
commands would place the work files on disks named TMPD and DEVD. 

$ ASSIGN TMPD: SORTWORKO 

$ ASSIGN DEVD: S0RTW0RK1 

Using more than two work files (the default) is not particularly advan¬ 
tageous unless you have to use many smaller ones in order to fit on 
crowded disks. In fact, the amount of work files you use can be a dis¬ 
advantage. You can control the number of work files with the /WORK- 
FILES qualifier. 

Also, when CONVERT uses SORT32, it may open up to 13 files. If your 
process open file limit is reached or if RMS runs out of dynamic memory, 
SORT32 may fail to open a necessary temporary file. 

The default is /SORT. Also, this option is ignored if the output file is not 
indexed. 

For more information on using SORT32 with CONVERT, see the /FAST- 
LOAD qualifier in this section. 
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CONVERT 

/SORT 


EXAMPLES 

□ $ CONVERT/SORT IN_ISAM.DAT OUT_ISAM.DAT 

This command causes the records in the input indexed file IN_ISAM.DAT 
to be sorted according the primary key values before being loaded into the 
output indexed file OUT__ISAM.DAT. 

s $ CONVERT/NOSORT/FDL=REORG ISAM.DAT ISAM.DAT 

This command reorganizes the file ISAM.DAT according to the attributes 
specified in the FDL file REORG.FDL. The primary keys are not sorted 
because ISAM.DAT is already in order by primary key, and the primary key 
definition did not change. 
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CONVERT 

/STATISTICS 


/STATISTICS 

Determines whether a set of statistics about the completed con¬ 
version will be displayed. This qualifier can be used on both the 
CONVERT and the CONVERT/RECLAIM commands. 


FORMAT /[NO]STATISTICS 

qualifier values None. 


DESCRIPTION Both CONVERT and CONVERT/RECLAIM have a /STATISTICS command 

qualifier. The statistics produced by the Convert Utility are listed below. 

• Number of files processed 

• Total records processed 

• Total exception records 

• Total valid records 

• Elapsed time 

• Buffered I/O count 

• Direct I/O count 

• Page faults 

• CPU time 

The statistics produced by the Convert/Reclaim Utility are listed below. 

• Total buckets scanned 

• Data buckets reclaimed 

• Index buckets reclaimed 

• Total buckets reclaimed 

• Elapsed time 

• CPU time 

CONVERT/RECLAIM produces no output unless you specify this qualifier. 


EXAMPLES 

□ $ CONVERT/STATISTICS Q3_SALES.DAT YTD_SALES.DAT 

This command causes CONVERT to load the records from the input file 
Q3_SALES.DAT into the output file YTD_SALES.DAT and then display a set 
of statistics about the conversion. 
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CONVERT 

/STATISTICS 


B $ CONVERT/RECLAIM/STATISTICS CUSTDATA.IDX 

This command causes CONVERT/RECLAIM to reclaim buckets in the 
indexed file CUSTDATA.IDX and then to display statistics about the 
reclamation. 
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CONVERT 

/TRUNCATE 


/TRUNCATE 

Specifies whether long records are to be truncated. 


FORMAT 

/[NO]TRUNCATE 

qualifier values 

None. 

DESCRIPTION 

A record is too long when it exceeds the maximum record length of the file or 
the record length for fixed-length record format. 

If a long record is encountered and /NOTRUNCATE is specified, the record is 
not written to the output file. If the /EXCEPTIONS— FILE option is specified, 
the entire record is written to the exceptions file. 


EXAMPLES 

□ $ CONVERT/TRUNCATE INFILE.DAT OUTFILE.DAT 

This command causes CONVERT to truncate any records from the input 
file INFILE.DAT that are too long for the specifications of the output file 
OUTFILE.DAT. 

S $ CONVERT/NOTRUNCATE/EXCEPTIONS_FILE=EXFILE INFILE OUTFILE 

This command causes CONVERT to write any records from the input file 
INFILE that are too long for the specifications of the output file OUTFILE to 
the exceptions file EXFILE. 
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CONVERT 

/WORK_ FILES 


/WORK_ FILES 

Specifies the number of temporary work files to be used during the 
sort process. 


FORMAT /WORK—FILES = n 


qualifier value n 

Specifies the number of work files you want. You can specify 0 or any value 
from 1 through 10. A value of 0 indicates that no work files are necessary 
because the data will fit into your process's working set. 

The default number of work files used during a sort is 2. 


DESCRIPTION This option is valid when you are fast-loading a file with multiple keys or 

when you specify the /SORT qualifier. For more information on sorting, see 
both the /SORT and the /FAST—LOAD qualifiers in this section. 


EXAMPLE 

$ C0NVERT/W0RK_FILES=0 UPDATE.DAT MASTER.DAT 

This command loads the records from the input file UPDATE.DAT into the 
output file MASTER.DAT without using any work files. 
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CONVERT 

/WRITE_CHECK 


/WRITE_CHECK 



Specifies whether all writes are to be checked by reading the new 
records from the disk and comparing the new records with the 
original records in memory. 

FORMAT 

/[NO]WRITE_CHECK 

qualifier values 

None. 


EXAMPLE 

$ CONVERT/WRITE.CHECK UPDATE.DAT MASTER.DAT 

This command causes CONVERT to load the records from the input file 
UPDATE.DAT into the output file MASTER.DAT and then compare the 
written records with the original records for accuracy. 
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CONVERT 

Examples 




CONVERT 

EXAMPLES 

□ $ CONVERT/NOCREATE/TRUNCATE/EXCEPTIONS_FILE=EXFILE VARFILE.DAT FIXFILE.DAT 

This command causes CONVERT to copy records from a file with 
variable-length records (VARFILE.DAT) to a file with fixed-length records 
(FIXFILE.DAT). Records longer than the fixed length are truncated, and short 
records are copied to the exceptions file EXFILE.EXC. 

0 $ CONVERT FILE.IDX FILE.IDX 

This command creates the output file FILE.IDX with a version number one 
higher than that of the input file. The output file is a copy of the input file, 
but it is a clean copy without bucket splits, RRVs (record reference vectors), 
or pointers to deleted records. The performance of the output file is also 
improved. 

Note that CONVERT establishes new RFAs during such reorganizations. 

E $ CONVERT/RECLAIM/STATISTICS FILE.IDX 

This command reclaims empty buckets in the file FILE.IDX. RFA values are 
preserved. 

Q $ CONVERT/FDL=TEST.FDL TRNTO::DBA1:[EXP]SUB.DAT OUT.DAT 

This CONVERT command creates a new sequential file OUT.DAT with 
stream record format at the local node, according to the specification in the 
previously created FDL file TEST.FDL. The input file SUB.DAT at remote 
node TRNTO is sequential with variable-length record format. The Convert 
Utility copies records from SUB.DAT to OUT.DAT, changing the format of 
the records. 

The contents of the FDL file TEST.FDL are as follows: 

SYSTEM 

SOURCE VAX/VMS 

FILE 

ORGANIZATION SEQUENTIAL 

RECORD 

BLOCK.SPAN YES 

CARRIAGE.CONTROL CARRIAGE.RETURN 
FORMAT STREAM 

SIZE 0 

E $ CONVERT MASTER.DAT DENVER::DB1:[PROD]MASTER.SAV 

This CONVERT command creates a new file called MASTER.SAV at remote 
node DENVER from the file MASTER.DAT at the local node. Because the 
/FDL qualifier is not used, the new file has the same file organization and 
record format as the original file. The action of this CONVERT command 
is similar to the function performed by the COPY command. However, 
CONVERT transfers the file record by record and thus does not use block 
I/O. 
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CONVERT 

Examples 


E $ CONVERT/APPEND SALES.TMP KANSAS::[200,2]SALES.CMD 

This CONVERT command causes records from the file SALES.TMP at the lo¬ 
cal node to be added sequentially to the end of the output file SALES.CMD at 
remote node KANSAS. The file SALES.TMP is sequential with variable-length 
record format, and the file SALES.CMD is sequential with stream record for¬ 
mat. When the Convert Utility loads records from the input file to the output 
file, it changes the record format. 

Q $ CONVERT/FDL=FIXED/PAD=0/TRUNCATE INFILE.VAR OUTFILE.FIX 

This command creates the fixed format file OUTFILE.FIX and then loads it 
with records from the variable input file INFILE.VAR. Before they are loaded, 
any short records from the input file are padded with an ASCII 0 character, 
and any long records are truncated. 

E $ CONVERT/FDL=SYS$INPUT FORT.DAT STREAM.DAT 
FILE 

ORGANIZATION SEQUENTIAL 

RECORD 

CARRIAGE.CONTROL CARRIAGE.RETURN 

_ FORMAT STREAM 

[CTRL/Zl 


This command converts the FORTRAN carriage control file FORT.DAT to a 
stream file that prints or types identically. The number of records may differ, 
and the FORTRAN carriage control information is removed from the records. 




$ CONVERT/FDL=SYS$INPUT FORT.DAT VAR.DAT 
FILE 

ORGANIZATION SEQUENTIAL 

RECORD 

CARRIAGE.CONTROL CARRIAGE.RETURN 

_ FORMAT VARIABLE 

1 CTRL/Zl 


This command converts the FORTRAN carriage control file FORT.DAT to 
a variable-length record file. The FORTRAN carriage control information is 
preserved as the first data byte, and the number of records in the output and 
input files is the same. 
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